home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / UI & Events / Opening a Part Into a Window < prev    next >
Encoding:
Text File  |  1995-11-07  |  6.9 KB  |  205 lines  |  [TEXT/ttxt]

  1. OpenDocâ„¢ Recipes
  2.  
  3. Opening a Part into a Window
  4. By The OpenDoc Design Team
  5. November, 1995
  6.  
  7.  
  8. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  11.  
  12.  
  13. Introduction
  14.  
  15. This document describes what you need to know to implement the Open() method of a part editor:
  16.  
  17. ODID Open(in ODFrame);
  18.  
  19. The Open() method is responsible for creating a window for the specified frame, and returning the ID of that window. If the window already exists, the method should simply activate it. The semantics are actually a little more complicated than this. 
  20.  
  21. Open a Part from Nothing
  22.  
  23. When a new document is created from stationery, it contains no window state. In this case the Open() method of the root part  is called by the OpenDoc shell, passing  kODNULL as the frame.
  24.  
  25. Open an Embedded Frame
  26.  
  27. When the user selects a frame and chooses Open Selection from the document menu, the active part calls the selected part's Open() method, passing in the selected frame. 
  28.  
  29. Open a Saved Document
  30.  
  31. New in DR2: When a document (actually a draft) is saved, the draft contains a list of root frames of persistently stored windows. OpenDoc annotates each root frame with a storage unit containing the window properties (bounding rectangle, etc.). When the document is opened, and the Window State internalized, the Window State calls the Open method of each frame's part, passing in the frame.  The implementor of the Open() method can distinguish this case because the frame is a root frame, and contains the annotations. Utility functions are provided to access the window properties. See Window Utilities in the Utilities documentation.
  32.  
  33. Note: This means that windows are ALWAYS created by the parts, even when opening a saved document. Thus parts can and should do whatever they need to to adjust the window size and position to a given monitor configuration.
  34.  
  35. New in DR3: When an embedded selection is dragged to the Finder, and the source of the drag clones the selected frame, OpenDoc adds the frame to the root frame list of the newly-created document. In this case the Open() method will be called, and passed a root frame that has no window properties attached. So the Open() method should not assume that window properties are there.
  36.  
  37. View In Window
  38.  
  39. This menu item is handled by the active part itself, so it does not need to go through the Open() protocol at all, though a part editor may call some of the same internal methods.
  40.  
  41.  
  42.  
  43. Sample Code
  44.  
  45. Below is an example implementation of the Open() method from the Clock Part. Note the use of the utility functions BeginGetWindowProperties and EndGetWindowProperties, from WinUtils.h. BeginGetWindowProperties takes a (root) frame, and returns the window properties in a convenient struct, so that the part editor doesn't need to deal with the Storage API directly.
  46.  
  47. SOM_Scope ODID  SOMLINK AppleTest_ClockOpen(AppleTest_Clock *somSelf, Environment *ev,
  48.          ODFrame*  frame )
  49. {
  50.     AppleTest_ClockData *somThis = AppleTest_ClockGetData(somSelf);
  51.     AppleTest_ClockMethodDebug("Clock","Open");
  52.     
  53.     SOM_CATCH return kODNULLID;
  54.  
  55.     ODID windowID;
  56.     ODWindow* window = kODNULL;
  57.     
  58.     if (frame) // Doing a View As Window or Opening a Root Frame
  59.     {
  60.         if (frame->IsRoot(ev))
  61.         {
  62.             windowID = _fClockPart->OpenRootFrame(ev, frame);
  63.         }
  64.         else
  65.         {
  66.             ClockFrame* clockFrame = (ClockFrame*) frame->GetPartInfo(ev);
  67.             if (clockFrame)
  68.                 windowID = clockFrame->ViewInWindow(ev);
  69.         }
  70.     }
  71.     else
  72.     {
  73.         windowID = _fClockPart->OpenInitialWindow(ev);
  74.     }
  75.     return windowID;
  76. }
  77.  
  78.  
  79. ODID ClockPart::OpenRootFrame(Environment *ev, ODFrame* frame)
  80. {
  81.     ODWindow* window = kODNULL;
  82.     ODID windowID = 0;
  83.     WindowProperties props;
  84.     
  85.     ODBoolean hasWindowProperties = BeginGetWindowProperties(ev, frame, &props);
  86.     if (!hasWindowProperties)
  87.         this->GetDefaultWindowProperties(ev, &props, kODNULL);
  88.     ODPlatformWindow platformWindow = this->CreatePlatformWindow(props);
  89.     ClockFrame* clockFrame = (ClockFrame*) frame->GetPartInfo(ev);
  90.     // Set the platform window early, so that if RegisterWindow fails, clockFrame
  91.     // can still get to the platform window to dispose of it.
  92.     if (clockFrame)
  93.         clockFrame->SetPlatformWindow(platformWindow); 
  94.     TRY{
  95.         window =  fSession->GetWindowState(ev)->RegisterWindowForFrame(ev, 
  96.                     platformWindow, 
  97.                     frame,
  98.                     props.isRootWindow,    // Keeps draft open
  99.                     kODTrue,    // Is resizable
  100.                     kODFalse,    // Is floating
  101.                     kODTrue,    // shouldSave
  102.                     kODFalse,    // should dispose
  103.                     props.sourceFrame);
  104.     }CATCH_ALL{
  105.         TRY{
  106.             EndGetWindowProperties(ev, &props); // Release source frame
  107.         }CATCH_ALL{
  108.             //ignore errors
  109.         }ENDTRY
  110.         RERAISE;
  111.     }ENDTRY
  112.     EndGetWindowProperties(ev, &props); // Release source frame
  113.     window->Open(ev);
  114.     window->Show(ev);
  115.     windowID = window->GetID(ev);
  116.     ODReleaseObject(ev, window);
  117.     return windowID;
  118. }
  119.  
  120. void ClockPart::GetDefaultWindowProperties(Environment* ev, WindowProperties* props, ODFrame* sourceFrame)
  121. {
  122.     CopyPascalString(props->title, "\pClock");
  123.     props->procID = zoomDocProc;
  124.     props->hasCloseBox = kODTrue;
  125.     props->refCon = 0;
  126.     props->wasVisible = kODTrue;
  127.     props->isResizable = kODTrue;
  128.     props->isFloating = kODFalse;
  129.     props->isRootWindow = (sourceFrame == kODNULL);
  130.     props->shouldShowLinks = kODFalse;
  131.     props->sourceFrame = sourceFrame;
  132.  
  133.     this->CalcClockBounds(props->boundsRect);
  134.     if (!fAnalog)
  135.     {
  136.         props->boundsRect.right += 15;
  137.         props->boundsRect.bottom += 15;
  138.     }
  139.     OffsetRect(&props->boundsRect, 40, 40);
  140.  
  141.     ODName* windowName = kODNULL;
  142.     if (sourceFrame)
  143.         windowName = ODGetPartName(ev, sourceFrame, kODNULL);
  144.     if (windowName==kODNULL || GetITextStringLength(windowName)==0)
  145.         CopyPascalString(props->title, "\pClock");
  146.     else
  147.         GetITextPString(windowName, props->title);
  148.     if (windowName)
  149.         DisposeIText(windowName);
  150. }
  151.  
  152. ODID ClockPart::OpenInitialWindow(Environment *ev)
  153. {
  154.     ODWindow* window = kODNULL;
  155.     WindowProperties props;
  156.     this->GetDefaultWindowProperties(ev, &props, kODNULL);
  157.  
  158.     window = this->CreateWindow(ev, props, kODNULL);
  159.     ODID windowID = window->GetID(ev);
  160.     window->Open(ev);
  161.     window->Show(ev);
  162.     window->Select(ev);    
  163.     ODReleaseObject(ev, window);    
  164.     return windowID;            
  165. }
  166.  
  167. ODID ClockTimeFrame::ViewInWindow(Environment *ev)
  168. {
  169.     ODWindow* window = kODNULL;
  170.     
  171.     window = fWindowState->AcquireWindow(ev, fWindowID);
  172.     if (window)
  173.     {
  174.         window->Select(ev);
  175.         ODReleaseObject(ev, window);    
  176.     }
  177.     else
  178.     {
  179.         WindowProperties props;
  180.         fClockPart->GetDefaultWindowProperties(ev, &props, fFrame);
  181.         window = fClockPart->CreateWindow(ev, props, kODNULL);
  182.         fWindowID = window->GetID(ev);
  183.         window->Open(ev);
  184.         window->Show(ev);
  185.         window->Select(ev);    
  186.         ODReleaseObject(ev, window);        
  187.     }
  188.     return fWindowID;
  189. }
  190.  
  191. ODPlatformWindow ClockPart::CreatePlatformWindow(WindowProperties& props)
  192. {
  193.     ODPlatformWindow platformWindow = NewCWindow(
  194.         (Ptr)ODNewPtr(sizeof(WindowRecord)), // Create it in the OpenDoc heap
  195.         &(props.boundsRect), 
  196.         props.title, 
  197.         kODFalse /*visible */, 
  198.         props.procID, 
  199.         (WindowPtr)-1L, 
  200.         props.hasCloseBox, 
  201.         props.refCon);
  202.     return platformWindow;
  203. }
  204.  
  205.